/*------------------------------------------------------------------------
|                            FILE DESCRIPTION                            |
------------------------------------------------------------------------*/
/*------------------------------------------------------------------------
|  - File name     : stdint_os.h
|  - Author        : zeweni
|  - Update date   : 2021.03.23
|  - Copyright(C)  : 2021-2021 zeweni. All rights reserved.
------------------------------------------------------------------------*/
/*------------------------------------------------------------------------
|                            COPYRIGHT NOTICE                            |
------------------------------------------------------------------------*/
/*
 * Copyright (C) 2021, zeweni (17870070675@163.com)

 * This file is part of Ant Real Time Operating System.

 * Ant Real Time Operating System is free software: you can redistribute 
 * it and/or modify it under the terms of the Apache-2.0 License.

 * Ant Real Time Operating System is distributed in the hope that it will 
 * be useful,but WITHOUT ANY WARRANTY; without even the implied warranty 
 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
 * Apache-2.0 License License for more details.

 * You should have received a copy of the Apache-2.0 License.Ant Real Time
 * Operating System. If not, see <http://www.apache.org/licenses/>.
**/

/*------------------------------------------------------------------------
|                                 INCLUDE                                |
------------------------------------------------------------------------*/
#ifndef __OS_MEM_H_
#define __OS_MEM_H_

#include "os_type.h"

/*------------------------------------------------------------------------
|                                  MACRO                                 |
------------------------------------------------------------------------*/

/* None. */

/*------------------------------------------------------------------------
|                                  DATA                                  |
------------------------------------------------------------------------*/

/**
 * @brief   内存初始化函数，对内存池和内存堆进行初始化，
 *          分静态和动态两部分，内核主要使用静态方法。
 * @details The memory initialization function initializes 
 *          the memory pool and memory heap,
 *          Divided into two parts, static and dynamic, 
 *          the kernel mainly uses static methods.
 * @param   None.
 * @return  [OS_OK] 内存初始化成功。 The memory is initialized successfully.
 * @return  [OS_NOK] 内存初始化失败。The memory initialization failed.
**/
os_err_t AntOS_Mem_Init(void);


/**
 * @brief      动态申请内存函数。
 * @details    Dynamic application memory function.
 * @param[in]  ptr 要申请内存的指针。The pointer to apply for memory.
 * @param[in]  size 内存大小。 memory size.
 * @return     [address] 内存申请成功，返回内存块首地址给ptr指针。
 *             The memory application is successful, 
 *             and the first address of the memory block is returned for ptr.
 * @return     [OS_NULL] 内存申请失败，返回NULL空指针给ptr指针。
 *             The memory application is failed, 
 *             and the NULL pointer is returned for ptr.
 * @note       分配内存的过程分两步：
 *             1.先从内存池的顶部获取一段空间存放内存块信息头，方向是向下生成；
 *             2.再从内存池的底部获取一段空间存放内存块储存区，方向是向上生长。
 *	           The process of allocating memory is divided into two steps:
 *             1. First obtain a space from the top of the memory pool to store 
 *             the memory block information header, and the direction is to generate downwards;
 *             2. Get a space from the bottom of the memory pool to store the memory block storage area, 
 *             and the direction is to grow upward.
 *        	   Icon:
 *
 *             ----------------                                    ----------------
 *             | 内存池-信息头 |                                    | 内存池-信息头 | 
 *             ----------------                                    ----------------
 *             | 内存块1信息头 |                                    | 内存块1信息头 | 
 *             ----------------                                    ---------------- 
 *             |              |           分配一块内存              | 内存块2信息头 | 
 *             ----------------          ============>             ---------------- 
 *             |              |                                    |              |
 *             ----------------                                    ----------------
 *             |              |                                    |              |
 *             ----------------                                    ----------------
 *             |              |                                    | 内存块2存储区 |
 *             ----------------                                    ----------------
 *             | 内存块1存储区 |                                    | 内存块1存储区 | 
 *             ----------------                                    ---------------- 
**/
extern void *OS_Malloc(void *mptr,os_size_t msize);


/**
 * @brief      释放内存函数,支持内存碎片整理。
 * @details    Free memory function, Does support memory defragmentation.
 * @param[in]  ptr 要释放内存的指针。The pointer to free for memory.
 * @return     [OS_OK] 内存释放成功。
 *             The memory free is successful.
 * @return     [OS_NOK] 内存释放失败，返回NULL空指针给ptr指针。
 *             The memory free is failed.
 * @note       内存块被释放以后，排在这个内存块后面的内存块，会被全部移动，
 *             以填补空出来的位置，同时再更新被移动后的所有内存块的信息头，
 *             关键点是，更新处理信息头里面申请内存块的指针为被移动后的地址。
 * 			   After the memory block is released, 
 *             all the memory blocks behind this memory block will be moved.
 * 			   To fill in the vacant positions, and at the same time update 
 *             the information headers of all memory blocks that have been moved,
 *             The key point is that the pointer of the application memory block 
 *             in the update processing information header is the address after being moved.
 *        	   Icon:
 *
 *             ----------------                                    ----------------
 *             | 内存池-信息头 |                                    | 内存池-信息头 | 
 *             ----------------                                    ----------------
 *             | 内存块1信息头 |                                    | 内存块2信息头 | 
 *             ----------------                                    ---------------- 
 *             | 内存块2信息头 |            释放内存块1             |               | 
 *             ----------------          ============>             ---------------- 
 *             |              |                                    |              |
 *             ----------------                                    ----------------
 *             |              |                                    |              |
 *             ----------------                                    ----------------
 *             | 内存块2信息头 |                                    |              |
 *             ----------------                                    ----------------
 *             | 内存块1存储区 |                                    | 内存块2存储区 | 
 *             ----------------                                    ---------------- 
**/
extern os_err_t OS_Free(void *mptr);


/**
 * @brief      发送要被回收内存块的申请内存指针的地址。
 * @details    The address of the requested memory pointer to send the memory block to be reclaimed.
 * @param[in]  mptr 申请内存指针的地址。Address of the memory pointer.
 * @return     [OS_OK] 地址发送成功。
 *             The address was sent successfully.
 * @return     [OS_NOK] 地址发送失败。
 *             Failed to send the address.
**/
extern os_err_t OS_Mem_Send_Recycle_Addr(void *mpt);


/*------------------------------------------------------------------------
|                    END OF FLIE.  (C) COPYRIGHT zeweni                  |
------------------------------------------------------------------------*/

#endif